home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lantools / aplock / aplock.doc next >
Encoding:
Text File  |  1988-02-27  |  9.7 KB  |  223 lines

  1.  
  2.  
  3.  
  4.  
  5.                                    APLOCK 1.0
  6.                                   Tom Thompson
  7.  
  8.                         (C) Copyright 1988 by CBIS, Inc.
  9.                         5875 Peachtree Industrial Blvd
  10.                         Atlanta GA  30092
  11.                         (404) 446-1332
  12.  
  13.         APLOCK is used to synchronize network access to single user
  14.         applications.  Instead of running the application directly, a
  15.         BATCH file containing the name of the application and appropriate
  16.         APLOCK commands is executed.  The ERRORLEVEL codes returned by
  17.         APLOCK are used to control the flow of the BATCH program.
  18.         If you are familiar with constructing BATCH files to execute
  19.         other programs, then APLOCK'ed applications are easy to set up.
  20.  
  21.         Let's start with an example.  Assume that you have a program,
  22.         named ORDER.EXE, that everyone on the network needs to use.  It
  23.         can only be run by one person at a time.  Each person needs to
  24.         use it several times a day, but fairly infrequently and only for
  25.         a few minutes each time.   The multi-user version of ORDER is
  26.         either expensive or not-available, and it is too awkward to
  27.         always check to see if anyone is currently in the program as a
  28.         means of synchronization.
  29.  
  30.         This is a perfect application for APLOCK.  Set the system up as
  31.         follows:
  32.  
  33.              -    Everyone has access to the application in D:\APPS.
  34.              -    Everyone has access to a subdirectory E:\LOCKS (which
  35.                   will hold APLOCK control files).
  36.              -    ORDER.EXE is renamed to ORDERPRG.EXE.
  37.              -    Everyone has a path to the BATCH file ORDER.BAT
  38.                   (described below) and to APLOCK.EXE.
  39.              -    ORDER.BAT and APLOCK.EXE are set read-only with the
  40.                   ATTRIB command (ATTRIB +R filename).
  41.  
  42.         The contents of ORDER.BAT are shown below.  The line numbers are
  43.         for reference, and do not actually appear in the file.
  44.  
  45.          1  ECHO OFF
  46.          2  APLOCK LOCK E:\LOCKS\ORDER.LOK Program in use by $n since $t.
  47.          3  IF ERRORLEVEL 1 GOTO DONE
  48.          4  D:
  49.          5  CD\APPS
  50.          6  ORDERPRG
  51.          7  APLOCK UNLOCK E:\LOCKS\ORDER.LOK
  52.          8  :DONE
  53.  
  54.  
  55.  
  56.         Now, when ORDER is entered from the keyboard, the BATCH file
  57.         (instead of the program) is executed.  The first time APLOCK is
  58.         called (line 2), it looks to see if the file ORDER.LOK exists in the
  59.         E:\LOCKS directory.  There are three possibilities:
  60.  
  61.              (1)  ORDER.LOK does not exist.  In this case, APLOCK creates
  62.                   ORDER.LOK and stores in it the user's machine name and
  63.                   time of day.  APLOCK then returns with ERRORLEVEL 0.
  64.  
  65.  
  66.              (2)  ORDER.LOK exists, and its contents indicate it was
  67.                   created earlier from this same machine.  In this case,
  68.                   APLOCK simply returns with ERRORLEVEL 0.
  69.  
  70.              (3)  ORDER.LOK exists and was created by another machine.
  71.                   In this case, APLOCK displays the message "Program in
  72.                   use by nnnn since hh:mm", where nnnn and hh:mm were
  73.                   stored in ORDER.LOK by another user.  APLOCK then
  74.                   returns with ERRORLEVEL 1.
  75.  
  76.         Now, when line 3 of the BATCH file is executed, it uses the
  77.         ERRORLEVEL from line 2 to determine whether to continue normally
  78.         to line 4, or skip down to line 8.  In other words, if some other
  79.         user had (via the BATCH file) already created an ORDER.LOK file,
  80.         then actual execution of the application is bypassed.
  81.  
  82.         Assume that APLOCK returned ERRORLEVEL 0 and the application is
  83.         run (lines 4, 5, and 6).  When the user exits the application,
  84.         control is returned to line 7 of the BATCH file, which invokes
  85.         APLOCK again.  However this time the "key word" is UNLOCK instead
  86.         of LOCK.  This causes APLOCK to go delete the file ORDER.LOK,
  87.         thereby "freeing" the application for use by another.
  88.  
  89.  
  90.         Four APLOCK commands are possible.  The syntax is shown below:
  91.  
  92.              APLOCK LOCK <lockfile> <message>
  93.  
  94.              APLOCK UNLOCK <lockfile>
  95.  
  96.              APLOCK KILL <lockfile>
  97.  
  98.              APLOCK CLEANUP <lockfile> [<lockfile2> ... ]
  99.  
  100.         For the discussion below, these four formats will be referred to
  101.         as the LOCK, UNLOCK, KILL and CLEANUP commands respectively.
  102.         <lockfile> is the path/name of a control file used by APLOCK.  It
  103.         is unique for a given application.  <message> is displayed by the
  104.         LOCK command whenever the use of the application cannot be
  105.         acquired.  It can include the special strings $n, $d, and $t.
  106.         These will be replaced by the name, lock date, and lock time of
  107.         the user that has locked the application.
  108.  
  109.  
  110.  
  111.                                   LOCK Command
  112.  
  113.         This command returns ERRORLEVEL 0 if <lockfile> does not exist or
  114.         if it exists and the contents of <lockfile> indicate it was
  115.         created by the same machine (that's executing the LOCK command).
  116.         If <lockfile> does exist and was created by another user, then
  117.         ERRORLEVEL 1 is returned and <message> is displayed.  If a
  118.         "system error" exists, then ERRORLEVEL 2 is returned.  See below
  119.         for more information on system errors.
  120.  
  121.  
  122.                                  UNLOCK Command
  123.  
  124.         This command checks for the presence of <lockfile>.  If it exists
  125.         and it's contents indicate it was created by the same user, it is
  126.         deleted.  ERRORlevel 0 is returned.  If a "system error" exists,
  127.         then ERRORLEVEL 1 is returned.  See below for more information on
  128.         system errors.
  129.  
  130.  
  131.                                   KILL Command
  132.  
  133.         KILL is used to delete <lockfile> regardless of which user is
  134.         created.  This returns ERRORLEVEL 0 (or 1 if a system error
  135.         exists).  Referring to the example presented earlier, assume that
  136.         a user executing ORDER.BAT turned off the machine and went home
  137.         just as line 5 was being executed (and locked her office!).  This
  138.         would leave <lockfile> created and not "deletable" with the
  139.         UNLOCK command.  You could make a batch file called OVERRIDE that
  140.         contained the following:
  141.  
  142.          1  ECHO OFF
  143.          2  APLOCK LOCK E:\LOCKS\ORDER.LOK Locked by $n since $t.
  144.          3  IF NOT ERRORLEVEL 1 GOTO NOTLOCKED
  145.          4  ECHO About to override! Control-C, then Y to cancel!
  146.          5  PAUSE
  147.          6  APLOCK KILL E:\LOCKS\ORDER.LOK
  148.          7  :NOTLOCKED
  149.  
  150.  
  151.  
  152.                                  CLEANUP Command
  153.  
  154.         CLEANUP takes multiple <lockfile> arguments.  For each <lockfile>
  155.         it looks to see if it exists and was created by the same user.
  156.         If so, that file is deleted.  CLEANUP returns ERRORLEVEL 0 (or 1
  157.         for a system error).  This should be put in AUTOEXEC.BAT (or
  158.         similar startup point).  For example, if the user reset the
  159.         machine just as line 5 in the main example was being executed,
  160.         and
  161.  
  162.              APLOCK CLEANUP E:\LOCKS
  163.  
  164.         was in the start-up batch files (after network setup), then the
  165.         locked condition would be "cleaned up" before anybody noticed.
  166.  
  167.  
  168.  
  169.                                   SYSTEM ERRORS
  170.  
  171.         As in any multi-user program, there is always a small period of
  172.         time when a program is executing that files are open, records are
  173.         locked, etc. and loss of power or control at the user machine
  174.         will leave files inaccessible by other users.  If this happens to
  175.         APLOCK, an appropriate error message is printed and the file is
  176.         identified.  Sometimes the network can correct this condition in
  177.         a few minutes (or sooner if the offending workstation is
  178.         restarted).  Some cases may require taking the server down and
  179.         bringing it back up.  Other "system errors" are more mundane --
  180.         things like invalid directory paths.  Shown below is the general
  181.         format of the error display, followed by a list of possible
  182.         errors.
  183.  
  184.              APLOCK ERROR: <error message>
  185.                            Command = <key word>, Filename = <lock file>
  186.  
  187.  
  188.                   -    Bad syntax
  189.                   -    Invalid path for create lock file
  190.                   -    Write error when creating lock file
  191.                   -    Timed out attempting to access lock file
  192.                        (Another user stuck?)
  193.                   -    Could not delete lock file
  194.                   -    Timed out attempting to delete lock file
  195.                        (Another user stuck?)
  196.                   -    Invalid path for lock file
  197.                   -    Cannot read lock file
  198.                   -    Bad data format in lock file
  199.  
  200.  
  201.         The time out errors take abount 10 seconds to occur, since it is
  202.         normal for the <lockfile> to be inaccessible for short periods of
  203.         time.
  204.  
  205.  
  206.  
  207.                                REMINDERS and HINTS
  208.  
  209.         Set APLOCK.EXE and batch files that call it read-only, so you
  210.         won't get sharing violations (or set them sharable with SATTRIB
  211.         or FLAG).
  212.  
  213.         You can lock more than just programs.  Everybody could use the
  214.         same program, but "lock" a subdirectory full of data files to be
  215.         processed by the program.
  216.  
  217.         Make sure that "E:\LOCKS" (for instance) really addresses the
  218.         same physical directory for every user.
  219.  
  220.         For added protection against the user running the program
  221.         directly, let the BATCH file NWUSE a drive containing the
  222.         application, then NWUSE /D it when done.
  223.  
  224.  
  225.